3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Managing Trackers

QuickDraw 3D provides routines that you can use to create and manipulate tracker objects.

Q3Tracker_New

You can use the Q3Tracker_New function to create a new tracker.



 
TQ3TrackerObject Q3Tracker_New (TQ3TrackerNotifyFunc notifyFunc);

notifyFunc: A pointer to a tracker notify function. See [link] for information on writing a tracker notify function.

DESCRIPTION

The Q3Tracker_New function returns, as its function result, a reference to a new tracker object. The notifyFunc parameter specifies the tracker's notify function, which is called whenever the position or orientation of the tracker changes. If you want to poll for such changes instead of being notified, set notifyFunc to NULL . The new tracker is active and has both its position threshold and its orientation threshold set to 0. If Q3Tracker_New cannot create a new tracker, it returns NULL .

Q3Tracker_GetNotifyThresholds

You can use the Q3Tracker_GetNotifyThresholds function to get the current notify thresholds of a tracker.



 
TQ3Status Q3Tracker_GetNotifyThresholds (

                     TQ3TrackerObject trackerObject, 

                     float *positionThresh, 

                     float *orientationThresh);

trackerObject: A tracker object.
positionThresh: On exit, the current position threshold of the specified tracker.
orientationThresh: On exit, the current orientation threshold (in radians) of the specified tracker.

DESCRIPTION

The Q3Tracker_GetNotifyThresholds function returns, in the positionThresh and orientationThresh parameters, the current position and orientation thresholds of the tracker specified by the trackerObject parameter. These thresholds determine whether or not a change in position or orientation is large enough to cause QuickDraw 3D to call the tracker's notify function. Both thresholds for a new tracker are set to 0.

Q3Tracker_SetNotifyThresholds

You can use the Q3Tracker_SetNotifyThresholds function to set the notify thresholds of a tracker.



 
TQ3Status Q3Tracker_SetNotifyThresholds (

                     TQ3TrackerObject trackerObject, 

                     float positionThresh, 

                     float orientationThresh);

trackerObject: A tracker object.
positionThresh: The desired position threshold of the specified tracker.
orientationThresh: The desired orientation threshold (in radians) of the specified tracker.

DESCRIPTION

The Q3Tracker_SetNotifyThresholds function sets the position and orientation thresholds of the tracker specified by the trackerObject parameter to the values in the positionThresh and orientationThresh parameters.

Q3Tracker_GetActivation

You can use the Q3Tracker_GetActivation function to get the activation state of a tracker.



 
TQ3Status Q3Tracker_GetActivation (

                     TQ3TrackerObject trackerObject, 

                     TQ3Boolean *active);

trackerObject: A tracker object.
active: On exit, a Boolean value that indicates whether the specified tracker is active (kQ3True ) or inactive (kQ3False ).

DESCRIPTION

The Q3Tracker_GetActivation function returns, in the active parameter, a Boolean value that indicates whether the tracker specified by the trackerObject parameter is currently active or inactive.

Q3Tracker_SetActivation

You can use the Q3Tracker_SetActivation function to set the activation state of a tracker.



 
TQ3Status Q3Tracker_SetActivation (

                     TQ3TrackerObject trackerObject, 

                     TQ3Boolean active);

trackerObject: A tracker object.
active: A Boolean value that indicates whether the specified tracker is to be made active (kQ3True ) or inactive (kQ3False ).

DESCRIPTION

The Q3Tracker_SetActivation function sets the activation state of the tracker specified by the trackerObject parameter to the value specified in the active parameter. If the activation state of a tracker is changed, the serial number of the tracker is incremented.

Q3Tracker_GetEventCoordinates

You can use the Q3Tracker_GetEventCoordinates function to get the settings (coordinates) of a tracker that were recorded at a particular moment (typically, the time of a button click) by a previous call to Q3Tracker_SetEventCoordinates .



 
TQ3Status Q3Tracker_GetEventCoordinates (

                     TQ3TrackerObject trackerObject, 

                     unsigned long timeStamp, 

                     unsigned long *buttons, 

                     TQ3Point3D *position, 

                     TQ3Quaternion *orientation);

trackerObject: A tracker object.
timeStamp: A time stamp.
buttons: On exit, the button state value of the specified tracker at the specified time.
position: On exit, the position of the specified tracker at the specified time. If the tracker is absolute, this parameter contains the absolute coordinates of the tracker. If the tracker is relative, this parameter contains the change in position since the last call to Q3Tracker_GetEventCoordinates .
orientation: On exit, the orientation of the specified tracker at the specified time.

DESCRIPTION

The Q3Tracker_GetEventCoordinates function returns, in the buttons , position , and orientation parameters, the button state value, position, and orientation of the tracker specified by the trackerObject parameter, at the time specified by the timeStamp parameter. You can set any of the buttons , position , and orientation parameters to NULL to prevent Q3Tracker_GetEventCoordinates from returning a value in that parameter.

Q3Tracker_GetEventCoordinates selects the set of event coordinates whose time stamp is closest to the value specified in the timeStamp parameter. Any event coordinate sets that are older are discarded from the tracker's ring buffer. If the ring buffer is empty, Q3Tracker_GetEventCoordinates returns kQ3Failure .

Q3Tracker_SetEventCoordinates

You can use the Q3Tracker_SetEventCoordinates function to record the settings (coordinates) of a tracker at a particular time.



 
TQ3Status Q3Tracker_SetEventCoordinates (

                     TQ3TrackerObject trackerObject, 

                     unsigned long timeStamp, 

                     unsigned long buttons, 

                     const TQ3Point3D *position, 

                     const TQ3Quaternion *orientation);

trackerObject: A tracker object.
timeStamp: A time stamp.
buttons: The button state value of the specified tracker, or NULL .
position: The position of the specified tracker, or NULL .
orientation: The orientation (in radians) of the specified tracker, or NULL .

DESCRIPTION

The Q3Tracker_SetEventCoordinates function places into the ring buffer of event coordinates for the tracker specified by the trackerObject parameter the values specified in the buttons , position , and orientation parameters. The event coordinates are marked with the time stamp specified by the timeStamp parameter. If the tracker's ring buffer is full, the oldest item in the buffer is discarded.

A tracker's ring buffer can contain up to 10 items. Time stamps of items in the buffer increase from oldest to newest.

Q3Tracker_GetButtons

You can use the Q3Tracker_GetButtons function to get the button state of a tracker.



 
TQ3Status Q3Tracker_GetButtons (

                     TQ3TrackerObject trackerObject, 

                     unsigned long *buttons);

trackerObject: A tracker object.
buttons: On exit, the current button state value of the specified tracker.

DESCRIPTION

The Q3Tracker_GetButtons function returns, in the buttons parameter, the current button state of the tracker specified by the trackerObject parameter.

Q3Tracker_ChangeButtons

You can use the Q3Tracker_ChangeButtons function to change the button state of a tracker.



 
TQ3Status Q3Tracker_ChangeButtons (

                     TQ3TrackerObject trackerObject, 

                     TQ3ControllerRef controllerRef, 

                     unsigned long buttons, 

                     unsigned long buttonMask);

trackerObject: A tracker object.
controllerRef: A reference to a controller.
buttons: The desired button state value of the specified tracker.
buttonMask: A button mask.

DESCRIPTION

The Q3Tracker_ChangeButtons function sets the button state of the tracker specified by the trackerObject parameter to the value specified in the buttons parameter. The buttonMask parameter specifies a button mask for the tracker. A bit in the mask should be set if the corresponding button has changed since the last call to Q3Tracker_ChangeButtons .

The notify function of the specified tracker object may be called when the Q3Tracker_ChangeButtons function is executed. If, however, the tracker is inactive when Q3Tracker_ChangeButtons is called, the tracker's activation count for the buttons is updated but the notify function is not called.

The controllerRef parameter is used only by the tracker's notify function.

Q3Tracker_GetPosition

You can use the Q3Tracker_GetPosition function to get the position of a tracker.



 
TQ3Status Q3Tracker_GetPosition (

                     TQ3TrackerObject trackerObject, 

                     TQ3Point3D *position, 

                     TQ3Vector3D *delta, 

                     TQ3Boolean *changed, 

                     unsigned long *serialNumber);

trackerObject: A tracker object.
position: On exit, the current position of the specified tracker.
delta: On exit, the change in position since the last call to Q3Tracker_GetPosition .
changed: On exit, a Boolean value that indicates whether the position or delta parameter was changed (kQ3True ) or not (kQ3False ).
serialNumber: On entry, a tracker serial number, or NULL . On output, the current tracker serial number.

DESCRIPTION

The Q3Tracker_GetPosition function returns, in the position parameter, the current position of the tracker specified by the trackerObject parameter. In addition, it can return, in the delta parameter, the relative change in position since the previous call to Q3Tracker_GetPosition .

On entry, if the value of delta is NULL , the relative contribution is combined into the reported position. If the value of delta is not NULL , then delta is set to the relative motion that has been accumulated since the previous call to Q3Tracker_GetPosition . In either case, the position accumulator is set to (0, 0, 0) by this function.

If the value of the serialNumber parameter is NULL , Q3Tracker_GetPosition fills in the position and delta parameters and returns the value kQ3True in the changed parameter. Otherwise, the value specified in the serialNumber parameter is compared with the tracker's current serial number. If the two serial numbers are identical, Q3Tracker_GetPosition leaves the two coordinate parameters and the serialNumber parameter unchanged and returns the value kQ3False in the changed parameter. If the two serial number differ, Q3Tracker_GetPosition fills in the two coordinate parameters, updates the serialNumber parameter, and returns the value kQ3True in the changed parameter.

If the specified tracker is inactive, then the position parameter is set to the point (0, 0, 0), the delta parameter is set to (0, 0, 0) if it is non-NULL , and the changed parameter is set to kQ3False if it is non-NULL .

Q3Tracker_SetPosition

You can use the Q3Tracker_SetPosition function to set the position of a tracker.



 
TQ3Status Q3Tracker_SetPosition (

                     TQ3TrackerObject trackerObject, 

                     TQ3ControllerRef controllerRef, 

                     const TQ3Point3D *position);

trackerObject: A tracker object.
controllerRef: A reference to a controller.
position: The desired position of the specified tracker.

DESCRIPTION

The Q3Tracker_SetPosition function sets the position of the tracker specified by the trackerObject and controllerRef parameters to the value specified in the position parameter. If the specified tracker is inactive, Q3Tracker_SetPosition has no effect.

Calling Q3Tracker_SetPosition might cause the notify function of the tracker to be called.

Q3Tracker_MovePosition

You can use the Q3Tracker_MovePosition function to move the position of a tracker relative to its current position.



 
TQ3Status Q3Tracker_MovePosition (

                     TQ3TrackerObject trackerObject, 

                     TQ3ControllerRef controllerRef, 

                     const TQ3Vector3D *delta);

trackerObject: A tracker object.
controllerRef: A reference to a controller.
delta: The desired change in position of the specified tracker.

DESCRIPTION

The Q3Tracker_MovePosition function adds the value specified by the delta parameter to the position of the tracker specified by the trackerObject and controllerRef parameters. If the specified tracker is inactive, Q3Tracker_MovePosition has no effect.

Calling Q3Tracker_MovePosition might cause the notify function of the tracker to be called.

Q3Tracker_GetOrientation

You can use the Q3Tracker_GetOrientation function to get the current orientation of a tracker.



 
TQ3Status Q3Tracker_GetOrientation (

                     TQ3TrackerObject trackerObject, 

                     TQ3Quaternion *orientation, 

                     TQ3Quaternion *delta, 

                     TQ3Boolean *changed, 

                     unsigned long *serialNumber);

trackerObject: A tracker object.
orientation: On exit, the current orientation of the specified tracker.
delta: On exit, the change in orientation since the last call to Q3Tracker_GetOrientation .
changed: On exit, a Boolean value that indicates whether the orientation or delta parameters was changed (kQ3True ) or not (kQ3False ).
serialNumber: On entry, a tracker serial number, or NULL . On output, the current tracker serial number.

DESCRIPTION

The Q3Tracker_GetOrientation function returns, in the orientation parameter, the current orientation of the tracker specified by the trackerObject parameter. In addition, it may return, in the delta parameter, the relative change in orientation since the previous call to Q3Tracker_GetOrientation .

On entry, if the value of delta is NULL , the relative contribution is combined into the reported orientation. If the value of delta is not NULL , then delta is set to the relative motion that has been accumulated since the previous call to Q3Tracker_GetOrientation . In either case, the orientation accumulator is set to identity by this function.

If the value of the serialNumber parameter is NULL , Q3Tracker_GetOrientation fills in the orientation and delta parameters and returns the value kQ3True in the changed parameter. Otherwise, the value specified in the serialNumber parameter is compared with the tracker's current serial number. If the two serial numbers are identical, Q3Tracker_GetOrientation leaves the two coordinate parameters and the serialNumber parameter unchanged and returns the value kQ3False in the changed parameter. If the two serial number differ, Q3Tracker_GetOrientation fills in the two coordinate parameters, updates the serialNumber parameter, and returns the value kQ3True in the changed parameter.

If the specified tracker is inactive, then the orientation parameter is set to identity, the delta parameter is set to identity if it is non-NULL , and the changed parameter is set to kQ3False if it is non-NULL .

Q3Tracker_SetOrientation

You can use the Q3Tracker_SetOrientation function to set the orientation of a tracker.



 
TQ3Status Q3Tracker_SetOrientation (

                     TQ3TrackerObject trackerObject, 

                     TQ3ControllerRef controllerRef, 

                     const TQ3Quaternion *orientation);

trackerObject: A tracker object.
controllerRef: A reference to a controller.
orientation: The desired orientation (in radians) of the specified tracker, or NULL .

DESCRIPTION

The Q3Tracker_SetOrientation function sets the orientation of the tracker specified by the trackerObject and controllerRef parameters to the value specified in the orientation parameter. If the specified tracker is inactive, Q3Tracker_SetOrientation has no effect.

Calling Q3Tracker_SetOrientation might cause the notify function of the tracker to be called.

Q3Tracker_MoveOrientation

You can use the Q3Tracker_MoveOrientation function to set the orientation of a tracker relative to its current orientation.



 
TQ3Status Q3Tracker_MoveOrientation (

                     TQ3TrackerObject trackerObject, 

                     TQ3ControllerRef controllerRef, 

                     const TQ3Quaternion *delta);

trackerObject: A tracker object.
controllerRef: A reference to a controller.
delta: The desired change in orientation of the specified tracker.

DESCRIPTION

The Q3Tracker_MoveOrientation function adds the value specified by the delta parameter to the orientation of the tracker specified by the trackerObject and controllerRef parameters. If the specified tracker is inactive, Q3Tracker_MoveOrientation has no effect.

Calling Q3Tracker_MoveOrientation might cause the notify function of the tracker to be called.